Methods and Events

The Dashboard widget supports the following interaction patterns:

• Direct Method Calls using the executeAction method.
• Event-Based Communication using custom events with promise-based responses.

Both approaches provide the same functionality with different implementation styles. You can programmatically control dashboard behavior (such as applying filters, switching versions, or triggering downloads) from your host application. You can also integrate dashboard actions into your UI workflows or automation scripts.

setUserFilters Method

Applies a set of filters to the widget’s current view. Useful for programmatically controlling the data display.

Syntax:

// Enables changes to the userFilters property.
const dashboardComponent = document.querySelector("qrvey-dashboard");
dashboardComponent.setUserFilters(filters);

Note: For parameter type filters, see Working With Filters in Embedded Scenarios.

executeAction Method

The executeAction method provides direct access to dashboard functionality through method calls on the dashboard element.

Syntax:

dashboard.executeAction(actionName, parameters)
  .then(response => {
    // Handle success
  })
  .catch(error => {
    // Handle error
  });

executeAction("atApplyUserFilters")

Applies user-defined filters to the dashboard data. This allows you to programmatically filter dashboard content based on specific criteria.

Applicable Views: Preview, Design and Interact

Property	Type	Required
filters	IFBUserFilters. For more information about the filter object, see Working With Filters in Embedded Scenarios.	Yes

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('atApplyUserFilters', {
  filters: [
    {
      operator: 'AND',
      expressions: [
        {
          qrveyid: 'syqssyvbr',
          questionid: 'f4koA2I1b',
          validationType: 'EQUAL',
          value: ['0 - 1 Solar Resource Assessment']
        }
      ]
    }
  ]
})
.then(result => console.log('Filters applied successfully:', result))
.catch(error => console.error('Failed to apply filters:', error));

---

executeAction("qvDSHGoToDashboardBack")

Execute the option of going back from the target dashboard to the original dashboard when a GoToDashboard action has been executed.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHGoToDashboardBack')
  .then(result => console.log('GotoDashbaord back action successful:', result))
  .catch(error => console.error('Error going back to original dashboard:', error));

---

executeAction("qvDSHRestoreDashboard")

Switches between different versions of the dashboard, allowing users to restore original, personalized, or handle non-existent versions. Indicates which dashboard version is being restored.

Applicable Views: Interact

Property	Type	Required
version	String. One of ORIGINAL, PERSONALIZED or NO-VERSION-EXISTS	Yes

const dashboard = document.querySelector('qrvey-dashboard');

// Restore original version
dashboard.executeAction('qvDSHRestoreDashboard', { version: 'ORIGINAL' })
  .then(result => console.log('Original version restored'))
  .catch(error => console.error('Failed to restore version:', error));

// Restore personalized version
dashboard.executeAction('qvDSHRestoreDashboard', { version: 'PERSONALIZED' })
  .then(result => console.log('Personalized version restored'))
  .catch(error => console.error('Failed to restore version:', error));

// Handle non-existent version
dashboard.executeAction('qvDSHRestoreDashboard', { version: 'NO-VERSION-EXISTS' })
  .then(result => console.log('Version handling completed'))
  .catch(error => console.error('Version does not exist:', error));

---

executeAction("qvDSHSaveDashboard")

Saves (interact mode) or publishes (design mode) the current state of the dashboard, persisting any changes made by the user.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHSaveDashboard')
  .then(result => console.log('Dashboard saved successfully:', result))
  .catch(error => console.error('Failed to save dashboard:', error));

---

executeAction("qvDSHUnpublishDashboard")

Unpublishes the dashboard, reverting it to an unpublished state. This action removes the dashboard from published/live status.

Applicable Views: Design

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHUnpublishDashboard')
  .then(result => console.log('Dashboard unpublished successfully:', result))
  .catch(error => console.error('Failed to unpublish dashboard:', error));

---

executeAction("qvDSHDownloadDashboard")

Triggers a download of the dashboard, opening the modal to configure the download or to schedule a report/export file. The format attribute is required for the download.

Applicable Views: Design and Interact

Property	Type	Required
format	String. One of PDF, CSV, EXCEL or DATASET	Yes

const dashboard = document.querySelector('qrvey-dashboard');

// Download as PDF
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'PDF' })
  .then(result => console.log('PDF download initiated'))
  .catch(error => console.error('PDF download failed:', error));

// Download as CSV
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'CSV' })
  .then(result => console.log('CSV download initiated'))
  .catch(error => console.error('CSV download failed:', error));

// Download as Excel
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'EXCEL' })
  .then(result => console.log('Excel download initiated'))
  .catch(error => console.error('Excel download failed:', error));

// Download as Dataset
dashboard.executeAction('qvDSHDownloadDashboard', { format: 'DATASET' })
  .then(result => console.log('Dataset download initiated'))
  .catch(error => console.error('Dataset download failed:', error));

---

executeAction("qvDSHUndo")

Reverts the last action performed on the dashboard.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHUndo')
  .then(result => console.log('Last action undone:', result))
  .catch(error => console.error('Undo failed:', error));

---

executeAction("qvDSHRedo")

Reapplies a previously undone action.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHRedo')
  .then(result => console.log('Action redone:', result))
  .catch(error => console.error('Redo failed:', error));

---

executeAction("qvDSHDiscardChanges")

Discards all unsaved changes made to the dashboard, reverting to its last saved state.

Applicable Views: Design and Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHDiscardChanges')
  .then(result => console.log('Changes discarded:', result))
  .catch(error => console.error('Failed to discard changes:', error));

---

executeAction("qvDSHHiddenItems")

Opens the hidden items panel, allowing users to view and restore previously hidden dashboard elements.

Applicable Views: Interact

const dashboard = document.querySelector('qrvey-dashboard');

dashboard.executeAction('qvDSHHiddenItems')
  .then(result => console.log('Hidden items panel opened:', result))
  .catch(error => console.error('Failed to open hidden items:', error));

---

Incoming Events (Custom Events Listened By Widget)

The dashboard supports event-based communication using custom events. You can dispatch events directly and handle them as needed. However, to obtain a response from the dashboard, you can listen for a result event by adding a Result suffix to the event name (for example, dispatching qvDSHSaveDashboard and listening for qvDSHSaveDashboardResult). The following helper function demonstrates this pattern with promise-based handling, but you can implement your own event-handling approach.

Helper Function:

function dispatchWithResponse(eventName, detail) {
  return new Promise((resolve, reject) => {
    const resultEvent = `${eventName}Result`;
    const onResult = (event) => {
      event.detail.success 
        ? resolve(event.detail.data) 
        : reject(new Error(event.detail.error));
      document.removeEventListener(resultEvent, onResult);
    };
    document.addEventListener(resultEvent, onResult);
    document.dispatchEvent(new CustomEvent(eventName, { detail }));
  });
}

// Usage wrapper
function callDispatch(eventName, detail={}) {
  dispatchWithResponse(eventName, detail)
    .then(res => console.log(`[Event] ${eventName} SUCCESS`, detail, res))
    .catch(err => console.log(`[Event] ${eventName} ERROR`, detail, err.message));
}

atApplyUserFilters

Triggers the process of applying user filters to the dashboard, similar to the apply-user-filters method.

Applicable Views: Preview, Design and Interact

Property	Type	Required
filters	IFBUserFilters. For more information about the filter object, see Working With Filters in Embedded Scenarios.	Yes

dispatchWithResponse('atApplyUserFilters', {
  filters: [
    {
      operator: 'AND',
      expressions: [
        {
          qrveyid: 'syqssyvbr',
          questionid: 'f4koA2I1b',
          validationType: 'EQUAL',
          value: ['0 - 1 Solar Resource Assessment']
        }
      ]
    }
  ]
})
.then(result => console.log('Filters applied via event:', result))
.catch(error => console.error('Event-based filter application failed:', error));

---

qvDSHRestoreDashboard

Requests the restoration of the dashboard to a previous saved state. Indicates which dashboard version is being restored. Only valid versions (ORIGINAL or PERSONALIZED) are allowed.

Applicable Views: Interact

Property	Type	Required
version	String. Either 'ORIGINAL', 'PERSONALIZED'	Yes

// Restore original version
dispatchWithResponse('qvDSHRestoreDashboard', { version: 'ORIGINAL' })
  .then(result => console.log('Original version restored via event'))
  .catch(error => console.error('Event-based restore failed:', error));

// Restore personalized version
dispatchWithResponse('qvDSHRestoreDashboard', { version: 'PERSONALIZED' })
  .then(result => console.log('Personalized version restored via event'))
  .catch(error => console.error('Event-based restore failed:', error));

---

qvDSHSaveDashboard

Initiates the dashboard save operation, persisting all current modifications.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHSaveDashboard')
  .then(result => console.log('Dashboard saved via event:', result))
  .catch(error => console.error('Event-based save failed:', error));

---

qvDSHUnpublishDashboard

Initiates the dashboard unpublish operation, reverting the dashboard to an un unpublished state and removing it from published status.

Applicable Views: Design

dispatchWithResponse('qvDSHUnpublishDashboard')
  .then(result => console.log('Dashboard unpublished via event:', result))
  .catch(error => console.error('Event-based unpublish failed:', error));

---

qvDSHDownloadDashboard

Triggers a download of the dashboard, opening the modal to configure the download or schedule, usually as a report or export file. The format attribute is required for the download.

Applicable Views: Design and Interact

Property	Type	Required
format	String. One of PDF, CSV, EXCEL. DATASET or JSON	Yes

// Download as PDF via event
dispatchWithResponse('qvDSHDownloadDashboard', { format: 'PDF' })
  .then(result => console.log('PDF download initiated via event'))
  .catch(error => console.error('Event-based PDF download failed:', error));

// Download as CSV via event
dispatchWithResponse('qvDSHDownloadDashboard', { format: 'CSV' })
  .then(result => console.log('CSV download initiated via event'))
  .catch(error => console.error('Event-based CSV download failed:', error));

---

qvDSHGoToDashboardBack

Executes the option of going back from the target dashboard to the original dashboard when a GoToDashboard action has been executed.

dispatchWithResponse('qvDSHGoToDashboardBack')
  .then(result => console.log('GoToDashboardBack action successful:', result))
  .catch(error => console.error('Error going back to original dashboard:', error));

---

qvDSHUndo

Triggers the undo operation for the most recent dashboard action.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHUndo')
  .then(result => console.log('Last action undone via event:', result))
  .catch(error => console.error('Event-based undo failed:', error));

---

qvDSHRedo

Triggers the redo operation for the most recently undone action.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHRedo')
  .then(result => console.log('Action redone via event:', result))
  .catch(error => console.error('Event-based redo failed:', error));

---

qvDSHDiscardChanges

Requests a discard of all pending modifications to the dashboard.

Applicable Views: Design and Interact

dispatchWithResponse('qvDSHDiscardChanges')
  .then(result => console.log('Changes discarded via event:', result))
  .catch(error => console.error('Event-based discard failed:', error));

---

qvDSHHiddenItems

Opens the hidden elements modal where deleted dashboard items can be reviewed or restored.

Applicable Views: Interact

dispatchWithResponse('qvDSHHiddenItems')
  .then(result => console.log('Hidden items panel opened via event:', result))
  .catch(error => console.error('Event-based hidden items failed:', error));

---

Outgoing Events (Custom Events Emitted By Widget)

The dashboard wisget emits custom DOM events to notify your host application about important actions or state changes within the dashboard, such as when a page loads, filters are applied, or a download completes. Listen for these events to react to dashboard activity, update your UI, or trigger additional logic in your application.

qvDSHPageLoaded

Emitted when the dashboard page has fully loaded and is ready for interaction. Indicates which dashboard version has been loaded (SOURCE, PERSONALIZED).

Applicable Views: Preview, Design and Interact

document.addEventListener('qvDSHPageLoaded', (event) => {
  console.log('Dashboard page loaded and ready');
  // Initialize any dashboard-dependent functionality here
});

---

qvDSHItemsLoaded

Emitted when all visible dashboard items (panels) have been successfully loaded.

Applicable Views: Preview, Design and Interact

document.addEventListener('qvDSHItemsLoaded', (event) => {
  console.log('Dashboard items loaded successfully');
  // Perform actions that depend on dashboard items being available
});

---

qvDSHHiddenItemsResult

Emitted when the hidden items modal has been opened.

Applicable Views: Interact

document.addEventListener('qvDSHHiddenItemsResult', (event) => {
  console.log('Hidden items result:', event.detail);
  if (event.detail.success) {
    console.log('Hidden items accessed successfully');
  } else {
    console.error('Error accessing hidden items:', event.detail.error);
  }
});

---

qvDSHGoToDashboardBackResult

Emitted after the qvDSHGoToDashboardBack operation has finished, reporting the current state. It can be built using the Go Back button, event, or method.

Applicable Views: Interact

document.addEventListener('qvDSHGoToDashboardBackResult', (event) => {
  console.log('Dashboard go back result:', event.detail);
  if (event.detail.success) {
    console.log('Go back to dashboard executed successfully');
  } else {
    console.error('Error going back from dashboard:', event.detail.error);
  }
});

---

qvDSHGoToDashboardResult

Emitted after the GoToDashboard or drill-down to a dashboard action has finished, reporting the current state. This is triggered by a click that performs the action, rather than executing GotToDashboard from an event or method.

Applicable Views: Interact

document.addEventListener('qvDSHGoToDashboardResult', (event) => {
  console.log('Go to dashboard result:', event.detail);
  if (event.detail.success) {
    console.log('Go to dashboard executed successfully');
  } else {
    console.error('Error going to dashboard:', event.detail.error);
  }
});

---

Error Handling

Direct method calls and event-based communication provide comprehensive error handling:

• Success responses contain the operation result data.
• Error responses include detailed error information.
• Network or system errors are caught and can be handled appropriately.

Always implement proper error handling to ensure a robust user experience:

// Example with comprehensive error handling
dashboard.executeAction('download', { format: 'PDF' })
  .then(result => {
    console.log('Download successful:', result);
    // Handle successful download
  })
  .catch(error => {
    if (error.response) {
      console.error('Server error:', error.response);
      // Handle server-side errors
    } else {
      console.error('Client error:', error.message);
      // Handle client-side errors
    }
  });